cursor

Type

property

Summary

Specifies the shape of the cursor.

Syntax

set the cursor to {<cursorName> | <imageID>}

Description

Use the cursor property to signal the status of a handler to the user or to indicate what kind of data the mouse pointer is over. For example, a watch cursor shows the user that a handler is executing, while an I-beam cursor indicates that the text under the mouse pointer is editable.

LiveCode looks for the specified image in the following order:

1. The stack of the current object's behavior (if applicable)
2. The stack of the owner of the current object's behavior (if applicable)
3. The stack of the current object's stack's behavior (if applicable)
4. The current object's stack
5. The current object's stack's mainstack (if a substack)
6. The current object's stack's mainstacks substacks
7. The list of open stacks, in order they were loaded

LiveCode includes several built-in cursors whose names you can use in place of their image IDs.

The built-in cursors and their recommended uses are:

• none: Hides the cursor
• busy: Use repeatedly during a long handler
• watch: Use during a moderately long handler
• arrow: Use for selecting objects
• cross: Use for painting, drawing, or selecting a point or small area
• hand: Use for clicking hypertext links
• iBeam: Use for selecting text in a field
• plus: Use for selecting items such as spreadsheet cells
• help: Use for getting online help

The busy cursor is a rotating beach ball. Each time you use the statement set the cursor to busy, the beach ball advances in its rotation. For example, the following statements cause the cursor to appear to spin as long as the repeat loop is running:

    repeat until someCondition is true
        set the cursor to busy -- spins a bit further
        doSomething -- insert whatever you want the loop to do here
    end repeat

You can also set the cursor property to the ID of an image. Custom cursor images must contain three colors: black, white, and a transparent color.

Cross-platform note

• Windows XP and above support full alpha-blended cursors up to 64x64
• More recent Linux distributions support alpha-blended cursors up to a size of 64x64
• Mac OS X supports alpha-blended cursors up to 256x256

note

Alpha-blending support depends on the current screen depth on some platforms.

If the lockCursor property is set to false, LiveCode automatically sets the cursor according to its location once the handler finishes. (For example, the cursor normally turns into an arrow over a menu, an I-beam over an editable text field, and so on.) To retain the cursor property after a handler finishes, use the lock cursor command.

You can force LiveCode to use the operating system's cursors with the following two statements:

    delete stack \"revCursors\"
    reset cursors

Caution! If you use the delete stack command to remove the "revCursors" stack, LiveCode's cursors are permanently deleted and you will need to download a new cursors stack to restore them.

If you change the set of built-in LiveCode cursors in the "revCursors" stack, you must either quit and restart the application or use the reset cursors command to begin using the new cursor shapes.

Examples

set the cursor to watch

set the cursor to arrow

set the cursor to 21403

Related

glossary: property, select, loop, handler, execute, download, cursor, hypertext, mouse pointer, command

keyword: image, field, items, point

object: stack, image

property: cursor, yHot, lockCursor, ID

command: lock cursor, delete stack

control structure: repeat

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

Platforms

desktop

server